package cn.song.freight.annotation;

import cn.song.freight.enums.ModuleType;
import cn.song.freight.enums.OperationType;

import java.lang.annotation.*;

/**
 * 操作日志注解
 * <pre>
 * 该注解用于标记需要记录操作日志的方法，支持自动记录操作日志。
 * 通过AOP切面拦截标记了该注解的方法，自动记录操作前后的数据变化。
 *
 * 使用方式：
 * 在需要记录日志的Controller或Service方法上添加该注解，
 * 指定模块类型、操作类型和操作描述等信息。
 *
 * 示例：
 * {@literal @}OperationLog(
 *     moduleType = ModuleType.AREA,
 *     operationType = OperationType.INSERT,
 *     description = "新增区域信息"
 * )
 * public Boolean addArea(AreaAddDTO addDTO) {
 *     // 方法实现
 * }
 *
 * @author SongRenShuo
 * @version 1.0.0
 * @since 2025-08-29
 */
@Target(ElementType.METHOD)
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface OperationLog {

    /**
     * 模块类型
     * 指定当前操作属于哪个模块
     */
    ModuleType moduleType();

    /**
     * 操作类型
     * 指定当前操作的类型（新增、修改、删除等）
     */
    OperationType operationType();

    /**
     * 操作描述
     * 详细描述当前操作的内容和目的
     */
    String description() default "";

    /**
     * 业务名称字段
     * 指定从参数中获取业务名称的字段名，支持嵌套属性
     * 例如：name、user.name、area.provinceName等
     */
    String businessNameField() default "";

    /**
     * 业务ID字段
     * 指定从参数中获取业务ID的字段名，支持嵌套属性
     * 例如：id、areaId、user.id等
     */
    String businessIdField() default "";

    /**
     * 是否记录请求参数
     * 默认为true，记录方法的请求参数
     */
    boolean recordRequestParams() default true;

    /**
     * 是否记录返回结果
     * 默认为false，不记录方法的返回结果（避免数据过大）
     * 设置为true时，将响应结果作为操作后数据记录
     */
    boolean recordResult() default false;

    /**
     * 是否记录响应结果
     * 默认为true，记录接口的完整响应结果（包含code、msg等）
     * 与recordResult不同，这里记录的是接口响应体，而不是业务数据
     */
    boolean recordResponseResult() default true;

    /**
     * 是否忽略异常
     * 如果设置为true，即使日志记录失败也不会影响原方法的执行
     * 默认为true，保证业务操作的正常进行
     */
    boolean ignoreException() default true;
}